# Basic config

## root

- **Type**: `string`
- **Default**: `docs`

Specifies the document root directory. For example:

```ts title="rspress.config.ts" twoslash
import { defineConfig } from '@rspress/core';

export default defineConfig({
  root: 'docs',
});
```

This config supports both relative and absolute paths, with relative paths being relative to the current working directory(cwd).

Of course, in addition to specifying the document root directory through the config file, you can also specify it through command line parameters, such as:

```bash
rspress dev docs
rspress build docs
```

## base

- **Type**: `string`
- **Default**: `/`

Deployment base path. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then you should set `base` to `"/bar/"`:

```ts title="rspress.config.ts" twoslash
import { defineConfig } from '@rspress/core';

export default defineConfig({
  base: '/bar/',
});
```

## title

- **Type**: `string`
- **Default**: `"Rspress"`

Site title. This parameter will be used as the title of the HTML page. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  title: 'My Site',
});
```

## description

- **Type**: `string`
- **Default**: `""`

Site description. This will be used as the description of the HTML page. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  description: 'My Site Description',
});
```

## icon

- **Type**: `string | URL`
- **Default**: `""`

Site icon. This path will be used as the icon path for the HTML page. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  icon: '/favicon.ico',
});
```

For normal path, Rspress will find your icon in the `public` directory, of course you can also set it to a CDN address, or use the `file://` protocol or `URL` to use local absolute path.

## lang

- **Type**: `string`
- **Default**: `""`

Default language of the site. See [Internationalization](/guide/default-theme/i18n) for more details.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  lang: 'en',
  locales: [
    {
      lang: 'en',
      // ...
    },
    {
      lang: 'zh',
      // ...
    },
  ],
});
```

## i18nSource

- **Type**: `Record<string, Record<string, string>> | ((value: Record<string, Record<string, string>>) => Record<string, Record<string, string>> | Promise<Record<string, Record<string, string>>>)`
- **Default**: `{}`

You can use this configuration to modify Rspress's built-in i18n text or extend custom component text. When extending text, it is usually used together with [useI18n](/ui/hooks/use-i18n.html).

:::tip

This has the same implementation and effect as `i18n.json`. You can use either one. `i18nSource` has higher priority than `i18n.json` and supports functions.

:::

The `i18nSource` parameter is an object with the following structure:

```ts
{
  [textKey: string]: {
    [locale: string]: string;
  }
}
```

Where the first-level `textKey` is the text key name, the second-level `locale` is the language code (e.g., `zh`, `en`), and the value is the translated text for the corresponding language.

Here is an example of modifying Rspress's built-in i18n text:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
export default defineConfig({
  i18nSource: {
    editLinkText: {
      en: '📝 Edit this page on Gitlab',
      zh: '📝 在 Gitlab 上编辑此页',
    },
  },
});
```

`i18nSource` can also be a function, for example:

```ts
import { defineConfig } from '@rspress/core';

export default defineConfig({
  i18nSource: async (source) => {
    for (const key of Object.keys(source)) {
      source[key]['en_US'] = source[key]['en'];
    }
    return source;
  },
});
```

Here are the built-in i18n texts in Rspress:

<details>

```ts file="../../../../../packages/core/src/node/runtimeModule/DEFAULT_I18N_TEXT.ts"

```

</details>

## logo \{#logo-1}

- **Type**: `string | { dark: string; light: string }`
- **Default**: `""`

Site logo. This path will be used as the logo path in the upper left corner of the navbar. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  logo: '/logo.png',
});
```

Rspress will find your icon in the `public` directory, you can also set it to a CDN address.

Of course you can set different logos for dark/light mode:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  logo: {
    dark: '/logo-dark.png',
    light: '/logo-light.png',
  },
});
```

## logoText

- **Type**: `string`
- **Default**: `""`

Site logo Text. This text will be used as the logo text in the upper left corner of the navbar. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  logoText: 'rspress',
});
```

## outDir

- **Type**: `string`
- **Default**: `doc_build`

Custom output directory for built sites. for example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  outDir: 'doc_build',
});
```

## locales

- **Type**: `Locale[]`

```ts
export interface Locale {
  lang: string;
  label: string;
  title?: string;
  description?: string;
}
```

I18n config of the site. for example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  locales: [
    {
      lang: 'en-US',
      label: 'English',
      title: 'My Site',
      description: 'My site description',
    },
    {
      lang: 'zh-CN',
      label: '简体中文',
      title: '站点标题',
      description: '站点描述',
    },
  ],
});
```

## head

- **Type**: `string` | `[string, Record<string, string>]` | `(route) => string | [string, Record<string, string>] | undefined`
- Can be appended per page via [frontmatter](./config-frontmatter.mdx#head)

Used to set additional elements rendered in the `<head>` tag of the page's HTML in production mode.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  // ... other user config
  head: [
    '<meta name="author" content="John Doe">',
    // or
    ['meta', { name: 'author', content: 'John Doe' }],
    // [htmlTag, { attrName: attrValue, attrName2: attrValue2 }]
    // or
    (route) => {
      if (route.routePath.startsWith('/jane/')) return "<meta name='author' content='Jane Doe'>";
      if (route.routePath.startsWith('/john/')) return ['meta', { name: 'author', content: 'John Doe' }];
      \\ or even skip returning anything
      return undefined;
    }
  ]
});
```

## mediumZoom

- **Type**: `boolean` | `{ selector?: string }`
- **Default**: `true`

Whether to enable the image zoom function. It is enabled by default, you can disable it by setting `mediumZoom` to `false`.

> The bottom layer is implemented using the [medium-zoom](https://github.com/francoischalifour/medium-zoom) library.

Example usage:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  // Turn off image zoom
  mediumZoom: false,
  // Configure the CSS selector to customize the picture to be zoomed, the default is '.rspress-doc img'
  mediumZoom: {
    selector: '.rspress-doc img',
  },
});
```

## search

- **Type**:

```ts
type SearchOptions = {
  searchHooks?: string;
  versioned?: boolean;
  codeBlocks?: boolean;
};
```

### searchHooks

- **Type**: `string`
- **Default**: `undefined`

You can add search runtime hooks logic through the `searchHooks` parameter, for example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  search: {
    searchHooks: path.join(__dirname, 'searchHooks.ts'),
  },
});
```

For specific hook logic, you can read [Customize Search Functions](/guide/advanced/custom-search).

### versioned

- **Type**: `boolean`
- **Default**: `false`

If you are using `multiVersion`, the `versioned` parameter allows you to create a separate search index for each version of your documentation.
When enabled, the search will only query the index corresponding to the currently selected version.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  search: {
    versioned: true,
  },
});
```

### codeBlocks

- **Type**: `boolean`
- **Default**: `true`

Whether to include code block content in the search index, which allows users to search code blocks.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  search: {
    codeBlocks: false,
  },
});
```

## globalUIComponents

- **Type**: `(string | [string, object])[]`
- **Default**: `[]`

You can register global UI components through the `globalUIComponents` parameter, for example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});
```

The item of `globalUIComponents` can be a string, which is the path of the component file, or an array, the first item is the path of the component file, and the second item is the component props, for example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  globalUIComponents: [
    [
      path.join(__dirname, 'components', 'MyComponent.tsx'),
      {
        foo: 'bar',
      },
    ],
  ],
});
```

import GlobalUIComponents from '../../fragments/global-ui-components.mdx';

<GlobalUIComponents />

## multiVersion

- **Type**: `{ default: string; versions: string[] }`

You can enable multi-version support through the `multiVersion` parameter, for example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});
```

The `default` parameter is the default version, and the `versions` parameter is the version list.

## route

- **Type**: `Object`

Custom route config.

### route.include

- **Type**: `string[]`
- **Default**: `[]`

Add some extra files in the route. By default, only the files in the document root directory will be included in the route. If you want to add some extra files to the route, you can use this option. For example:

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    include: ['other-dir/**/*.{md,mdx}'],
  },
});
```

> Note: The strings in the array support glob patterns, the glob expression should be based on the `root` directory of the document, with the corresponding extensions suffix.

:::note

We recommend using [addPages hook](/plugin/system/plugin-api.html#addpages) in a custom Rspress plugin to add some additional files to the route, so that the page route and file path/content can be specified more flexibly and reasonably.

:::

### route.exclude

- **Type**: `string[]`
- **Default**: `[]`

Exclude some files from the route. For example:

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    exclude: ['custom.tsx', 'component/**/*'],
  },
});
```

> Note: The strings in the array support glob patterns, the glob expression should be based on the `root` directory of the document.

### route.excludeConvention

- **Type**: `string[]`
- **Default**: `['**/_[^_]*']`

A [routing convention](../../guide/use-mdx/components.mdx) set for the convenience of users to use components in the [docs directory](/api/config/config-basic#root), which excludes files starting with `_` by default.

If you really need some routes starting with `_`, you can adjust this rule, for example, set it to exclude only files starting with `_fragment-`:

```js title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    excludeConvention: ['**/_fragment-*'],
  },
});
```

### route.extensions

- **Type**: `string[]`
- **Default**: `['.js', '.jsx', '.ts', '.tsx', '.md', '.mdx']`

The extensions of the files that will be included in the route. By default, Rspress will include all `'js'`, `'jsx'`, `'ts'`, `'tsx'`, `'md'`, `'mdx'` files in the route. If you want to customize the extensions, you can use this option. For example:

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    extensions: ['.md', '.mdx'],
  },
});
```

### route.cleanUrls

- **Type**: `Boolean`
- **Default**: `false`

Generate url without suffix when `cleanUrls` is `true` for shorter url link.

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    cleanUrls: true,
  },
});
```

## ssg

- **Type**: `boolean | { experimentalWorker?: boolean; experimentalLoose?: boolean; }`
- **Default**: `true`

Whether to enable static site generation. Rspress enable it by default to generate CSR outputs and SSG outputs.

If your document site is only required to be used in CSR scenarios, you can set `ssg` to `false`, and Rspress will only generate CSR outputs.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  ssg: false,
});
```

:::tip

SSG requires the source code to support SSR. If the code is not compatible to SSR, the build process will fail. You can try:

1. Fix code to make it SSR-compatible.

2. Set `ssg: false`, but the SSG feature will be lost.

:::

### experimentalWorker

- **Type**: `boolean`
- **Default**: `false`

After enabled, you can use worker to accelerate the SSG process and reduce memory usage. It is suitable for large document sites and is based on [tinypool](https://github.com/tinylibs/tinypool).

### experimentalExcludeRoutePaths

- **Type**: `(string | RegExp)[]`
- **Default**: `[]`

After enabled, some pages will not be rendered by SSG, and they will directly use html under CSR. This is suitable for SSG errors in large document sites bypassing a small number of pages. It is not recommended to enable this option actively.

## replaceRules

- **Type**: `{ search: string | RegExp; replace: string; }[]`
- **Default**: `[]`

You can set text replacement rules for the entire site through `replaceRules`. The rules will apply to everything including `_meta.json` files, frontmatter configurations, and document content and titles.

```ts title="rspress.config.ts"
export default {
  replaceRules: [
    {
      search: /foo/g,
      replace: 'bar',
    },
  ],
};
```

## languageParity

- **Type**: `Object`

Scans the `md` and `mdx` files in the document root directory to detect missing language versions, protect language parity.

### languageParity.enable

- **Type**: `boolean`
- **Default**: `false`

Whether to enable language parity checks.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  languageParity: {
    enabled: true,
  },
});
```

### languageParity.include

- **Type**: `string[]`
- **Default**: `[]`

Specifies the folders to be checked, defaulting to all files in the document root directory. Paths should be relative to each language directory. For example:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  languageParity: {
    // `posts/foods` and `articles` folders under the zh/en language directories
    include: ['posts/foods', 'articles'],
  },
});
```

### languageParity.exclude

- **Type**: `string[]`
- **Default**: `[]`

Excludes certain folders and files from the checks.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  languageParity: {
    exclude: ['excluded-directory', 'articles/secret.md'],
  },
});
```
